Devices and Data Types

This section describes working with waveform-audio devices, and includes information on how to open, close and query them for their capabilities. It also describes how to keep track of the devices in a system by using device handles and device identifiers.

Opening Waveform-Audio Output Devices

Use the waveOutOpen2MUO.P_ function to open a waveform-audio output device for playback. This function opens the device associated with the specified device identifier and returns a handle of the open device by writing the handle of a specified memory location.

Some multimedia computers have multiple waveform-audio output devices. Unless you want to open a specific waveform-audio output device in a system, you should use the WAVE_MAPPER flag for the device identifier when you open a device. The waveOutOpen function chooses the device in the system that is best able to play the specified data format.

Querying Audio Devices

Windows provides the following functions to determine how many devices of a certain type are available in a system.

Audio devices are identified by a device identifier. The device identifier is determined implicitly from the number of devices present in a system. Device identifiers range from zero to one less than the number of devices present. For example, if there are two waveform-audio output devices in a system, valid device identifiers are 0 and 1.

After you determine how many devices of a certain type are present in a system, you can use one of the following functions to query the capabilities of each device.

Each of these functions fills a structure with information about the capabilities of a specified device. The following table lists the structures that correspond to each of these functions.

Standard formats are listed in the dwFormats member of the WAVEOUTCAPS structure. Waveform-audio devices can support nonstandard formats. To determine whether a particular format (standard or nonstandard) is supported by a device, you can call the waveOutOpen2MUO.P_ function with the WAVE_FORMAT_QUERY flag. This flag does not open the device. You specify the format in question in the WAVEFORMATEX2R_J_MS structure pointed to by the pwfx parameter passed to waveOutOpen. For information about setting up this structure, see Devices and Data Types1WTW_.O.

Waveform-audio output devices vary in the capabilities they support. The dwSupport member of the WAVEOUTCAPS2IOYZJH structure indicates whether a device supports such capabilities as volume and pitch changes.

Device Handles and Device Identifiers

Each function that opens an audio device specifies a device identifier, a pointer to a memory location, and some parameters that are unique to each type of device. The memory location is filled with a device handle. Use this device handle to identify the open audio device when calling other audio functions.

The difference between identifiers and handles for audio devices is subtle but important:

    Device identifiers are determined implicitly from the number of devices present in a system. This number is obtained by using the auxGetNumDevs9HC3JZ, waveInGetNumDevs4N_N_MV, or waveOutGetNumDevs1_HR_R7 function.

    Device handles are returned when device drivers are opened by using the waveInOpenDZFQLF or waveOutOpen2MUO.P_ function.

There are no functions that open or close auxiliary audio devices. Auxiliary audio devices need not be opened and closed like waveform-audio devices because there is no continuous data transfer associated with them. All auxiliary audio functions use device identifiers to identify devices.

Waveform-Audio Output Data Types

The following data types are defined for waveform-audio output functions.

Specifying Waveform-Audio Data Formats

When you call the waveOutOpen2MUO.P_ function to open a device driver for playback or to query whether the driver supports a particular data format, use the pwfx parameter to specify a pointer to a WAVEFORMATEX2R_J_MS structure containing the requested waveform-audio data format. The WAVEFORMATEX structure is an extended version of the WAVEFORMAT3OFYOUD structure. It contains all the members of WAVEFORMAT, and adds two more: a wBitsPerSample member, which contains extra information required for the PCM (Pulse Code Modulation) format, and a cbSize member at the end. You can append data to the structure following cbSize as long as you fill cbSize with the size of the data. You can use the WAVEFORMATEX structure to describe PCM data, although you could also use the PCMWAVEFORMAT329HC5C structure. When the waveform-audio format type is not PCM, you must use WAVEFORMATEX instead of WAVEFORMAT.

The outmoded WAVEFORMAT structure does not contain all the information required to describe the PCM format. The PCMWAVEFORMAT structure includes a WAVEFORMAT structure along with an additional member containing PCM-specific information. The PCMWAVEFORMAT structure has also been superseded by the WAVEFORMATEX structure.

There are also two clipboard formats you can use to represent audio data: CF_WAVE and CF_RIFF. Use the CF_WAVE format to represent data in one of the standard formats, such as 11 kHz or 22 kHz PCM. Use the CF_RIFF format to represent more complex data formats that cannot be represented as standard waveform-audio files.

Writing Waveform-Audio Data

After successfully opening a waveform-audio output device driver, you can begin playing a sound. Windows provides the waveOutWrite12C9KIJ function for sending data blocks to waveform-audio output devices.

Use the WAVEHDR3CAL0JU structure to specify the waveform-audio data block you are sending using waveOutWrite. This structure contains a pointer to a locked data block, the length of the data block, and some flags. This data block must be prepared before you use it; for information about preparing a data block, see Audio Data BlocksFP81VZ.

After you send a data block to an output device by using waveOutWrite, you must wait until the device driver is finished with the data block before freeing it. If you are sending multiple data blocks, you must monitor the completion of data blocks to know when to send additional blocks. For more information about data blocks, see Audio Data BlocksFP81VZ.

PCM Waveform-Audio Data Format

The lpData member of the WAVEHDR3CAL0JU structure points to the waveform-audio data samples. For 8-bit PCM data, each sample is represented by a single unsigned data byte. For 16-bit PCM data, each sample is represented by a 16-bit signed value. The following table summarizes the maximum, minimum, and midpoint values for PCM waveform-audio data.

PCM Data Packing

The order of the data bytes varies between 8-bit and 16-bit formats and between mono and stereo formats. The following list describes data packing for the different PCM waveform-audio data formats.

Closing Waveform-Audio Output Devices

After waveform-audio playback is complete, call waveOutClose11Z3QHJ to close the output device. If waveOutClose is called while a waveform-audio file is playing, the close operation fails and the function returns an error code indicating that the device was not closed. If you do not want to wait for playback to end before closing the device, call the waveOutReset12_WU0Y function before closing. This ends playback and allows the device to be closed. Be sure to use the waveOutUnprepareHeader7UH.0HU function to clean up the preparation on all data blocks before closing the device.